Inside Macintosh: Open Transport /

Chapter 3 - Endpoints / Endpoints Reference

Functions / Establishing A Connection

OTConnect

Requests a connection to a remote peer.

C INTERFACE

OSStatus OTConnect(EndpointRef ref, TCall* sndCall, TCall* rcvCall);

C++ INTERFACE

OSStatus TEndpoint::Connect(TCall* sndCall, TCall* rcvCall);

PARAMETERS

ref

The endpoint reference of the endpoint initiating the connection.

sndCall

A pointer to a TCall structure (page 3-62) that specifies the address of the remote peer, any data transmitted when establishing a connection, and any options for this connection.

rcvCall

A pointer to a TCall structure (page 3-62) that specifies the address of the peer that has accepted the connection, the value of options proposed using the sndCall parameter, and any data transmitted by the peer accepting the connection.

This parameter is only meaningful for synchronous calls to the OTConnect function.

DESCRIPTION

If the endpoint is in synchronous mode, the OTConnect function returns after the connection is established and fills in the fields of the TCall structure (referenced by the rcvCall parameter) with the actual values associated with this connection. These might be different from the values you specified using the sndCall parameter.

If the OTConnect function returns with the kOTLookErr result, this might be either because of a pending T_LISTEN or T_DISCONNECT event. That is, either a connection request from another endpoint has interrupted execution of the function, or the remote endpoint has rejected the connection. If you don't have a notifier installed, you can call the OTLook function to identify the event that caused the kOTLookErr result. If the event is T_LISTEN, you must accept or reject the incoming request and then continue processing the OTConnect function by calling OTRcvConnect. If the event is T_DISCONNECT, you must call the OTRcvDisconnect function to clear the error condition--that is, to deallocate memory and place the endpoint in the correct state.

If the endpoint is in asynchronous mode, the OTConnect function returns before the connection is established with a kOTNoDataErr result to indicate that the connection is in progress. When the connection is established, the endpoint provider calls your notifier, passing T_CONNECT for the code parameter. In response, you must call the OTRcvConnect function to read the connection parameters that would have been returned using the rcvCall parameter if the endpoint were in synchronous mode.

It is possible that the remote address returned in the addr field of the rcvCall parameter is not the same as the address you requested using the sndCall->addr field. This happens when the connection is accepted for a different endpoint than the one receiving the connection request.

If the OTConnect function returns a result other than kOTNoDataErr, then the connection attempt has not been initiated and no events will be received.

SPECIAL CONSIDERATIONS

Not all endpoints support the sending of data with a connection request. Examine the connect field of the TEndpointInfo structure for the endpoint to determine if the endpoint supports the sending of data and to determine the maximum size of the data.

VALID STATES

T_IDLE

SEE ALSO

You can use the OTLook function (page 3-85) to retrieve a pending
asynchronous event.

You use a TCall structure (page 3-62) to specify the address of the remote peer, any data transmitted when establishing a connection, and any options for the connection.

You use the OTRcvDisconnect function (page 3-151) to acknowledge that your request for a connection has been rejected.

For information on how to use this function with a TCP/IP protocol, see page 8-17 in the TCP/IP chapter.

For information on how to use this function with AppleTalk protocols, see page 13-10 in the ADSP chapter and page 15-9 in the PAP chapter.

You examine the connect field of the TEndpointInfo structure (page 3-48) to determine whether your endpoint supports the sending of data with a connection request.